raven

Raven

Node v0.12/iojs compatible

Log errors and stack traces in Sentry from within your Node.js applications. Includes middleware support for Connect/Express.

All processing and sending happens asynchronously to not slow things down if/when Sentry is down or slow.

Compatibility

• 0.8.x
• 0.10.x
• 0.12.x
• iojs

Raven 0.7+ requires Sentry 6.4+

Installation

$ npm install raven

Methods

new raven.Client(String dsn[, Object options])
client.captureMessage(String message[[, Object options], Function callback])
client.captureError(Error error[[, Object options], Function callback])
client.captureQuery(String query[[, String type], Function callback])

Basic Usage

var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}');

client.captureMessage('Hello, world!');

You can specify a level in the second optional parameter. Default level is error

Sentry is aware of five different levels:

• debug (the least serious)
• info
• warning
• error
• fatal (the most serious)

var raven = require('raven');

var client = new raven.Client('{{ SENTRY_DSN }}', {level: 'warning'});

client.captureMessage("Another message")

Adding extra info an event

var raven = require('raven');

var client = new raven.Client('{{ SENTRY_DSN }}');

client.captureMessage("Another message", {extra: {'key': 'value'}})

Adding tags to an event

var raven = require('raven');

var client = new raven.Client('{{ SENTRY_DSN }}');

client.captureMessage("Another message", {tags: {'key': 'value'}})

Logging an error

client.captureError(new Error('Broke!'));

Logging a query

client.captureQuery('SELECT * FROM `awesome`', 'mysql');

Sentry Identifier

client.captureMessage('Hello, world!', function(result) {
    console.log(client.getIdent(result));
});

client.captureError(new Error('Broke!'), function(result) {
  console.log(client.getIdent(result));
});

Note: client.captureMessage will also return the result directly without the need for a callback, such as: var result = client.captureMessage('Hello, world!');

Events

If you really care if the event was logged or errored out, Client emits two events, logged and error:

client.on('logged', function(){
  console.log('Yay, it worked!');
});
client.on('error', function(e){
  console.log('oh well, Sentry is broke.');
})
client.captureMessage('Boom');

Error Event

The event error is augmented with the original Sentry response object as well as the response body and statusCode for easier debugging.

client.on('error', function(e){
  console.log(e.reason);  // raw response body, usually contains a message explaining the failure
  console.log(e.statusCode);  // status code of the http request
  console.log(e.response);  // entire raw http response object
});

Environment variables

SENTRY_DSN

Optionally declare the DSN to use for the client through the environment. Initializing the client in your app won't require setting the DSN.

SENTRY_NAME

Optionally set the name for the client to use. What is name?

SENTRY_RELEASE

Optionally set the application release version for the client to use, this is usually a Git SHA hash.

Catching global errors

For those times when you don't catch all errors in your application. ;)

client.patchGlobal();
// or
raven.patchGlobal(client);
// or
raven.patchGlobal('{{ SENTRY_DSN }}');

It is recommended that you don't leave the process running after receiving an uncaughtException (http://nodejs.org/api/process.html#process_event_uncaughtexception), so an optional callback is provided to allow you to hook in something like:

client.patchGlobal(function() {
  console.log('Bye, bye, world.');
  process.exit(1);
});

The callback is called after the event has been sent to the Sentry server.

Integrations

Connect/Express middleware

The Raven middleware can be used as-is with either Connect or Express in the same way.

Connect and Express

var connect = require('connect');
function mainHandler(req, res) {
  throw new Error('Broke!');
}
function onError(err, req, res, next) {
  // The error id is attached to `res.sentry` to be returned
  // and optionally displayed to the user for support.
  res.statusCode = 500;
  res.end(res.sentry+'\n');
}
connect(
  // Should be the first item listed
  raven.middleware.connect.requestHandler('{{ SENTRY_DSN }}'),

  connect.bodyParser(),
  connect.cookieParser(),
  mainHandler,

  // Should come before any other error middleware
  raven.middleware.connect.errorHandler('{{ SENTRY_DSN }}'),
  onError, // optional error handler if you want to display the error id to a user
).listen(3000);

Express

var app = require('express')();

app.get('/', function mainHandler(req, res) {
  throw new Error('Broke!');
});

// Should be the first item listed
app.use(raven.middleware.express.requestHandler('{{ SENTRY_DSN }}'));

// Should come before any other error middleware
app.use(raven.middleware.express.errorHandler('{{ SENTRY_DSN }}'));
app.use(onError); // optional error handler if you want to display the error id to a user

app.listen(3000);

Note: raven.middleware.express or raven.middleware.connect must be added to the middleware stack before any other error handling middlewares or there's a chance that the error will never get to Sentry.

Coffeescript

In order to use raven-node with coffee-script or another library which overwrites Error.prepareStackTrace you might run into the exception "Traceback does not support Error.prepareStackTrace being defined already."

In order to not have raven-node (and the underlying raw-stacktrace library) require Traceback you can pass your own stackFunction in the options. For example:

client = new raven.Client('{{ SENTRY_DSN }}', { stackFunction: {{ Your stack function }}});

So for example:

client = new raven.Client('{{ SENTRY_DSN }}', {
  stackFunction: Error.prepareStackTrace
});

Pre-processing data

Pass the dataCallback configuration value:

client = new raven.Client('{{ SENTRY_DSN }}', {
  dataCallback: function(data) {
    delete data.request.env;
    return data;
  }
});

Disable Raven

Pass false as the DSN (or any falsey value).

client = new raven.Client(process.env.NODE_ENV === 'production' && '{{ SENTRY_DSN }}')

Note: We don't infer this from NODE_ENV automatically anymore. It's up to you to implement whatever logic you'd like.

Support

You can find me on IRC. I troll in #sentry on freenode.